home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / util / cli / pipe3310.lha / pipe3310 / pipe.doc < prev   
Text File  |  1994-12-30  |  8KB  |  194 lines
  1. pipe                                     pipe
  2.  
  3.     NAME
  4.     pipe -- run commands and pipe their I/O together
  5.  
  6.     SYNOPSIS
  7.     pipe <command> | <command> ...
  8.  
  9.     DESCRIPTION
  10.     Pipe runs all the given shell commands and connects their I/O so that
  11.     pipe's  own  standard  input is  forwarded to the first command,  its
  12.     standard output to standard input of the next command and so on until
  13.     the  standard  output  of  the  last  command  is finally written out
  14.     through the standard output of the pipe itself.  All the commands are
  15.     launced  to  run  asynchronously and pipe itself waits until they all
  16.     have closed their standard input and standard output streams.
  17.  
  18.     Command lines to be run should be separated by vertical bar character
  19.     (|) from each other:
  20.  
  21.         pipe ilbmtoppm mypic.iff | ppmquant 256 | ppmtogif >mypic.gif
  22.  
  23.     will execute:
  24.         ilbmtoppm mypic.iff
  25.         ppmquant 256
  26.         ppmtogif
  27.  
  28.     If  the  separator character is located inside a double-quoted block,
  29.     pipe  won't recognize it as such,  so you can still use vertical bars
  30.     in your command lines:
  31.  
  32.         pipe search myfile "|" | wc
  33.  
  34.     will execute:
  35.         search myfile "|"
  36.         wc
  37.  
  38.     If the first word in the command line is quoted, pipe will remove the
  39.     quotes  before executing command.  This allows running command lines,
  40.     with vertical bars in them but which cannot accept the quotes:
  41.  
  42.         pipe ilbmtoppm mypic.iff | "pipe ppmquant 256 | ppmtogif" >my.gif
  43.  
  44.     will execute:
  45.         ilbmtoppm mypic.iff
  46.         pipe ppmquant 256 | ppmtogif
  47.  
  48.     In the above example the first pipe executes only two command lines -
  49.     ilbmtoppm  and  pipe.  The  other  pipe  then  executes  ppmquant and
  50.     ppmtogif. Other pipe never sees the quote characters.
  51.  
  52.     Note however,  that this feature forces you to quote the command name
  53.     twice if you want to execute command, which has spaces in its name.
  54.  
  55.         pipe "*"command with spaces*"" argument1 argument2 | ...
  56.     or
  57.         pipe "*"command with spaces*" argument1 argument2" | ...
  58.  
  59.     will execute:
  60.         "command with spaces" argument1 argument2
  61.         ...
  62.  
  63.     (The asterisks are here to escape the inner quotes)
  64.  
  65.     If  the  command is quoted only once, the shell executing the command
  66.     will  not  see the quotes and tries to execute just the first word of
  67.     the command name and give the rest to it as parameters:
  68.  
  69.         command with spaces argument1 argument2
  70.  
  71.     If you are using Amiga's ROM shell, executing command:
  72.  
  73.         set _pchar=|
  74.  
  75.     will  force the shell to automatically add command `pipe' in front of
  76.     any command  line  containing  vertical bars.  This allows you to use
  77.     pipe without typing it's name:
  78.  
  79.         ilbmtoppm mypic.iff | ppmquant 256 | ppmtogif >my.gif
  80.  
  81.     WHY TO USE
  82.     Several  different implementations of pipe exist.  Here are some good
  83.     reasons why you should use this particular one:
  84.  
  85.     Pipe implements its own pipe-handler, so id doesn't need PIPE: or any
  86.     other similar device to be mounted.
  87.  
  88.     Pipe  can  execute any command line the shell itself can.  The search
  89.     path is  traversed including the path-assigns,  resident programs are
  90.     checked, rexx-scripts with script flag set are automatically executed
  91.     and even the shell aliases work. This is possible by using the actual
  92.     shell to  actually execute the commands unlike some other implementa-
  93.     tions,  which use LoadSeg() and usually only support very limited set
  94.     of shell functions.
  95.  
  96.     Those  other  implementations,  which really use the shell to execute
  97.     the commands, usually don't forward the break signals to the executed
  98.     commands  because  there  is  no  straightforward way to find out the
  99.     process pointer of the command executed by shell. This implementation
  100.     modifies  exec's  AddTask() function to get the needed pointer so the
  101.     breaking is possible. If any of the CTRL-C/D/E/F signals is received,
  102.     it  will  be forwarded to all running commands in case of the CTRL-C,
  103.     all  the pipes  are  invalidated  so that also those programs,  which
  104.     don't respond to break will hopefully exit when their I/O fails.
  105.  
  106.     Pipe  copies  data straight form the buffer of the writing program to
  107.     the  buffer of  the  reading  program.  This  behaviour  has  several
  108.     advantages:
  109.  
  110.     - Only  one  buffer copy is needed.  The external pipe handlers first
  111.       copy the data  from  writer's  buffer to  their own buffer and then
  112.       from  there  to the reader's buffer.  This doubles the speed of the
  113.       data flow.
  114.  
  115.     - No memory is needed for the intermediate buffer.
  116.  
  117.     - Sizes  of the read and write operations are not limited by the size
  118.       of  the  intermediate  buffer  but only by the size of the opposing
  119.       ends I/O operation.  This makes the large data flows very effective
  120.       and is  comparable to  an using external pipe handler with infinite
  121.       buffer size.
  122.  
  123.     - Only  other  of  the  two programs is active at any particular time
  124.       while the  other is waiting  for  the  I/O to/from the other.  This
  125.       keeps  the system load  quite low when compared  to  buffering pipe
  126.       handlers which typically keep all the programs active simultaneous-
  127.       ly.  It  increases  the throughput by lowering context switch over-
  128.       head.
  129.  
  130.     SPECIAL NOTE
  131.     When pipe is executed the first time after a reboot,  it will install
  132.     a  modification  to  the AddTask() function of the exec.library.  The
  133.     modification  is left there and reused by subsequent pipe executions.
  134.     If  you  run some other software,  which SetFunction()s the AddTask()
  135.     function  and you want that the other software is also able to remove
  136.     it's modification,  you have to make sure that the pipe is not called
  137.     first  time  while the other modification is  active.  Easiest way to
  138.     do it is to run the pipe in system startup before the other modifying
  139.     program.  If  you  don't  have any other use for pipe in the startup-
  140.     sequence, you can make a dummy call:
  141.  
  142.         pipe ""
  143.  
  144.     Which  makes  the  pipe  to spawn a shell to execute an empty command
  145.     line  which effectively does  nothing.  the pipe however installs its
  146.     AddTask()  modification  and thus  makes  sure  that  nothing will be
  147.     installed later.  The  empty command line is required because if pipe
  148.     is  executed  with no parameters,  it will just display a short copy-
  149.     right and usage message and exit.
  150.  
  151.     LICENSE
  152.     Pipe may be freely distributed as long as no more is charged than the
  153.     cost  of  the  media.  You  may modify pipe or use it as part of some
  154.     other  product and  distribute  this  new  product  provided that the
  155.     original author name is not removed and the new product complies with
  156.     this distribution policy and if the pipe itself is modified, it has
  157.  
  158.         a different name
  159.     or
  160.         an extension appended to it's version number so that the original
  161.         version  can be read,  but it is clearly distinguishable from the
  162.         `official' version.  For example the original version number with
  163.         your initials appended.
  164.  
  165.     If you want to include pipe or parts of it in any commercial product,
  166.     please contact the author first.
  167.  
  168.     DISCLAIMER
  169.     Pipe is provided as is without any guarantee or warranty. Author is
  170.     not responsible for any damage or losses of any kind caused by the
  171.     use or misuse of the program and he is under no obligation to provide
  172.     service, corrections, or upgrades to this program.
  173.  
  174.     VERSION
  175.     This  manual is written 30th December 1994 and it covers pipe version
  176.     3.310.
  177.  
  178.     AUTHOR
  179.     Ville Saari
  180.  
  181.     Address: Tallbergin puistotie 7 B 21
  182.              00200 Helsinki
  183.              FINLAND
  184.  
  185.     Phone:   +358 0 682 2226
  186.  
  187.     Internet: vsaari@fipnet.fi
  188.  
  189.     If you find bugs in pipe, please let me know.
  190.  
  191.     Pipe is freely distributable,  but if you like it and absolutely want
  192.     to pay me something or give me a yacht or Ferrari or something,  then
  193.     do it.
  194.